IStorage - Compound File Implementation
The compound
file implementation of IStorage allows you to create and manage
substorages and streams within a storage object residing in a compound file
object. To create a compound file object and get an IStorage pointer,
call the API function StgCreateDocfile. To open an existing compound file object and
get its root IStorage pointer, call StgOpenStorage.
When to Use
Most
applications use this implementation to to create and manage storages and
streams.
Remarks
IStorage::CreateStream
Creates and
opens a stream object with the specified name contained in this storage object.
The OLE-provided compound file implementation of the IStorage::CreateStream
method does not support the following behaviors:
The STGM_DELETEONRELEASE flag is not
supported.
Transacted mode is not supported for stream
objects.
Opening the same stream more than once from
the same storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be
specified.
IStorage::OpenStream
Opens an
existing stream object within in this storage object using the specified access
modes specified in the grfMode parameter. The OLE-provided compound file
implementation of the IStorage::OpenStream method does not support the
following behavior:
The STGM_DELETEONRELEASE flag is not
supported.
Transacted mode is not supported for stream
objects.
Opening the same stream more than once from
the same storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be
specified.
IStorage::CreateStorage
The
OLE-provided compound file implementation of the IStorage::CreateStorage
method does not support the STGM_DELETEONRELEASE flag. Specifying this flag
causes the method to return STG_E_INVALIDFLAG.
IStorage::OpenStorage
Opens an
existing storage object with the specified name in the specified access mode.
The OLE-provided compound file implementation of the IStorage::OpenStorage
method does not support the following behavior:
The STGM_PRIORITY flag is not supported for
non-root storages.
Opening the same storage object more than
once from the same parent storage is not supported. The STGM_SHARE_EXCLUSIVE
flag must be specified.
The STGM_DELETEONRELEASE flag is not
supported. If this flag is specified, the function returns
STG_E_INVALIDFUNCTION.
IStorage::CopyTo
Copies only
the substorages and streams of this open storage object into another storage
object. The rgiidExclude parameter can be set to IID_IStream to copy
only substorages, or to IID_IStorage to copy only streams.
IStorage::MoveElementTo
Copies or
moves a substorage or stream from this storage object to another storage
object.
IStorage::Commit
Ensures that
any changes made to a storage object open in transacted mode are reflected in
the parent storage; for a root storage, reflects the changes in the actual
device, for example, a file on disk. For a root storage object opened in direct
mode, this method has no effect except to flush all memory buffers to the disk.
For non-root storage objects in direct mode, this method has no effect.
The
OLE-provided compound files implementation uses a two phase commit process
unless STGC_OVERWRITE is specified in the grfCommitFlags parameter. This
two-phase process ensures the robustness of data in case the commit operation
fails. First, all new data is written to unused space in the underlying file.
If necessary, new space is allocated to the file. Once this step has been
successfully completed, a table in the file is updated using a single sector
write to indicate that the new data is to be used in place of the old. The old
data becomes free space to be used at the next commit. Thus, the old data is
available and can be restored in case an error occurs when committing changes.
If STGC_OVERWRITE is specified, a single phase commit operation is used.
IStorage::Revert
Discards all
changes that have been made to the storage object since the last commit.
IStorage::EnumElements
Creates and
retrieves a pointer to an enumerator object that can be used to enumerate the
storage and stream objects contained within this storage object.The
OLE-provided compound file implementation takes a snapshot.
IStorage::DestroyElement
Removes the
specified element (substorage or stream) from this storage object.
IStorage::RenameElement
Renames the
specified substorage or stream in this storage object.
IStorage::SetElementTimes
Sets the
modification, access, and creation times of the specified storage element. The
OLE-provided compound file implementation maintains modification and change
times for internal storage objects. For root storage objects, whatever is
supported by the underlying file system (or ILockBytes) is supported. The
compound file implementation does not maintain any time stamps for internal
streams. Unsupported time stamps are reported as zero, enabling the caller to
test for support.
IStorage::SetClass
Assigns the
specified CLSID to this storage object.
IStorage::SetStateBits
Stores up to
32 bits of state information in this storage object. The state set by this
method is for external use only. The OLE-provided compound file implementation
does not perform any action based on the state.
IStorage::Stat
Retrieves the
STATSTG
structure for this open storage object.
See Also